home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD 2.1 / Amiga Developer CD v2.1.iso / CDTV / cdtvtools-11 / debox / doc / debox.doc
Encoding:
Text File  |  1991-06-24  |  15.5 KB  |  603 lines
  1. TABLE OF CONTENTS
  2.  
  3. debox.library/AllocBitMap
  4. debox.library/BMInfoSize
  5. debox.library/CenterViewPort
  6. debox.library/CheckHeader
  7. debox.library/CreateView
  8. debox.library/CycleColors
  9. debox.library/DecompBitMap
  10. debox.library/DecompBMInfo
  11. debox.library/DecompData
  12. debox.library/DeleteView
  13. debox.library/FreeBitMap
  14. debox.library/FreeBMInfo
  15. debox.library/HeaderSize
  16. debox.library/MemSet
  17. debox.library/NextComp
  18. debox.library/AllocBitMap                           debox.library/AllocBitMap
  19.  
  20.    NAME
  21.     AllocBitMap -- Allocates a BitMap structure and bitplanes.
  22.  
  23.    SYNOPSIS
  24.     bitmap = AllocBitMap (depth, width, height)
  25.       D0               D0      D1     D2
  26.  
  27.     struct BitMap * AllocBitMap (ULONG, ULONG, ULONG);
  28.  
  29.    FUNCTION
  30.     Allocates a bitmap structure and bitplanes (planes are in CHIP
  31.     memory).  If any part of it can't be allocated, NULL is returned,
  32.     and nothing will have been allocated.  Use FreeBitMap() to
  33.     deallocate the bitmap when finished.
  34.  
  35.     The routine allocates a standard BitMap structure unless the depth.
  36.     is greater than eight.  If more than eight bitplanes are requested,
  37.     AllocBitMap() will return a structure with the extra plane pointers at
  38.     the end of the structure.
  39.  
  40.    INPUTS
  41.     depth    - in planes.
  42.     width    - width in pixels.
  43.     height    - in pixels.
  44.  
  45.    RESULT
  46.     bitmap    - pointer to BitMap structure, suitably initialized, or NULL
  47.           if there's not enough memory.  The bitplanes themselves
  48.           are uninitialized i.e. garbage.
  49.  
  50.    EXAMPLE
  51.  
  52.    NOTES
  53.  
  54.    BUGS
  55.  
  56.    SEE ALSO
  57.     FreeBitMap()
  58.  
  59. debox.library/BMInfoSize                             debox.library/BMInfoSize
  60.  
  61.    NAME
  62.     BMInfoSize -- Returns the size of a picture's BMInfo structure.
  63.  
  64.    SYNOPSIS
  65.     size = BMInfoSize (header, data)
  66.      D0                A0        A1
  67.  
  68.     ULONG BMInfoSize (struct CompHeader *, UBYTE *);
  69.  
  70.    FUNCTION
  71.     Returns the bitmap info size for the current picture.  You would use
  72.     this if you wished to allocate memory for this data yourself instead
  73.     of having DecompBMInfo() allocate the memory automatically.  If
  74.     you were to do so, you may then pass the structure to
  75.     DecompBMInfo() while will fill it in with the picture's data.
  76.  
  77.     The function returns a positive value for success or a negitive
  78.     DEBOXERR value for failure.
  79.  
  80.    INPUTS
  81.     header    - pointer to a CompHeader structure or NULL.  If NULL then
  82.           the indata parameter is assumed to point to the CompHeader
  83.           structure (all sbox'ed data is in the form <header><data>).
  84.     indata    - pointer to the data to be decompressed.  If header is not
  85.           NULL then indata should be pointing to the <data> and not
  86.           the <header>.
  87.  
  88.    RESULT
  89.     size    - size of BMInfo structure, or negative DEBOXERR value if
  90.           an error occurred.
  91.  
  92.    EXAMPLE
  93.  
  94.    NOTES
  95.  
  96.    BUGS
  97.  
  98.    SEE ALSO
  99.     DecompBMInfo(), cdtv/debox.h
  100.  
  101. debox.library/CenterViewPort                     debox.library/CenterViewPort
  102.  
  103.    NAME
  104.     CenterViewPort -- Center a ViewPort on display.
  105.  
  106.    SYNOPSIS
  107.     CenterViewPort (view, viewport)
  108.              A0      A1
  109.  
  110.     void CenterViewPort (struct View *, struct ViewPort *);
  111.  
  112.    FUNCTION
  113.     Centers a ViewPort based on its modes and the View structure passed.
  114.     GfxBase->NormalDisplayColumns and GfxBase->NormalDisplayRows are
  115.     used to get proper screen placement.
  116.  
  117.     This routine is automatically called by CreateView().
  118.  
  119.    INPUTS
  120.     view     - pointer to a view structure with the DxOffset and
  121.            DyOffset already set.
  122.     viewport - pointer to an initialized ViewPort structure.
  123.  
  124.    RESULT
  125.  
  126.    EXAMPLE
  127.  
  128.    NOTES
  129.     Normally, if (viewport->DyOffset + view->DyOffset) < 13 then the
  130.     view is not shown.  CenterViewPort() makes sure that this
  131.     condition does not occur.
  132.  
  133.    BUGS
  134.     For screens much larger than normal overscan modes, the positioning
  135.     might be off.
  136.  
  137.    SEE ALSO
  138.     CreateView()
  139.  
  140. debox.library/CheckHeader                           debox.library/CheckHeader
  141.  
  142.    NAME
  143.     CheckHeader -- Check a debox header structure for validity.
  144.  
  145.    SYNOPSIS
  146.     error = CheckHeader (header)
  147.                      A0
  148.  
  149.     BYTE CheckHeader (struct CompHeader *);
  150.  
  151.    FUNCTION
  152.     Checks to see if 'header' is a valid CompHeader structure.  The
  153.     function returns a non-zero value if the header is invalid.
  154.  
  155.    INPUTS
  156.     header    - pointer to a CompHeader structure.
  157.  
  158.    RESULT
  159.     error    - zero (no error) if CompHeader is valid;  non-zero otherwise.
  160.  
  161.    EXAMPLE
  162.  
  163.    NOTES
  164.  
  165.    BUGS
  166.  
  167.    SEE ALSO
  168.  
  169. debox.library/CreateView                             debox.library/CreateView
  170.  
  171.    NAME
  172.     CreateView -- Creates a complete View out of a bitmap.
  173.  
  174.    SYNOPSIS
  175.     sv = CreateView (sv, bitmap, width, height, modes)
  176.     D0         A0    A1     D0      D1      D2
  177.  
  178.     struct SuperView * CreateView (struct SuperView *, struct BitMap *,
  179.                        UWORD, UWORD, UWORD);
  180.  
  181.    FUNCTION
  182.     Properly sets up a SuperView structure so that a LoadView() needs
  183.     only to be called to display the bitmap.  The width of the view
  184.     must be greater than 16.
  185.  
  186.     If 'sv' is NULL, the SuperView structure will be allocated by the
  187.     routine.  If this is the case the SuperView structure will have the
  188.     SV_ALLOCATED bit set and will be freed when DeleteView() is called.
  189.  
  190.     CreateView() calls CenterViewPort() in order to center the picture
  191.     on the screen.  It uses GfxBase->ActiView for its initial
  192.     view->DxOFfset and view->DyOffset values.
  193.  
  194.    INPUTS
  195.     sv    - a pointer to a SuperView structure or NULL.
  196.     bitmap    - a pointer to properly initialized BitMap structure.
  197.     width    - width of the ViewPort.
  198.     height    - height of the ViewPort.
  199.     modes    - ViewPort modes.  The special modes will be passed on to
  200.           the View structure.
  201.  
  202.    RESULT
  203.     sv    - pointer to a SuperView structure or NULL if there was
  204.           not enough memory and/or an error occurred.  It will also
  205.           return a NULL if 'width' <= 16.
  206.  
  207.    EXAMPLE
  208.  
  209.    NOTES
  210.  
  211.    BUGS
  212.     Creates bogus views when passed very small bitmaps.
  213.  
  214.    SEE ALSO
  215.     DeleteView(), CenterViewPort()
  216.  
  217. debox.library/CycleColors                           debox.library/CycleColors
  218.  
  219.    NAME
  220.     CycleColors -- Cycle the colormap according to the BMInfo structure.
  221.  
  222.    SYNOPSIS
  223.     changed = CycleColors (bminfo, microsec)
  224.       D0             A0      D0
  225.  
  226.     BOOL CycleColors (struct BMInfo *, ULONG);
  227.  
  228.    FUNCTION
  229.     Cycle the colors in the BMInfo.bmi_ColorMap according to the
  230.     information contained in bmi_RangeInfo.  Portions in bmi_RangeInfo
  231.     are also modified.
  232.  
  233.     Each time CycleColors is called each RangeInfo countdown timer is
  234.     modifed by the microsec value passed in D0.  When the RangeInfo
  235.     structure rgi_SecondsLeft and rgi_MicroLeft reach zero the
  236.     bmi_ColorMap is cycled accoring to that RangeInfo's information.  If
  237.     the colormap is modified, the function will return a nonzero
  238.     result.
  239.  
  240.     The best way to call this is in a vertical blank interrupt.  Pass
  241.     the cycleinfo and microsec equal to 16667 for NTSC or 20000 for PAL.
  242.     If CycleColors() returns nonzero, use LoadRGB4() to load the
  243.     modified palette into the ViewPort.
  244.  
  245.    INPUTS
  246.     bminfo     - A properly initilized BMInfo structure.
  247.     microsec - Micro seconds since last call.
  248.  
  249.    RESULT
  250.  
  251.    EXAMPLE
  252.  
  253.    NOTES
  254.     This function does not check to see if the color numbers contained
  255.     in RangeInfo->rgi_CArray are a valid range.  It is up to the program
  256.     or faith to check the RangeInfo structure for validity.  Also this
  257.     assumes the BMInfo and the RangeInfo structures have been correctly
  258.     set up.
  259.  
  260.    BUGS
  261.  
  262.    SEE ALSO
  263.     graphics.library/LoadRGB4(), cdtv/debox.h
  264.  
  265. debox.library/DecompBitMap                         debox.library/DecompBitMap
  266.  
  267.    NAME
  268.     DecompBitMap -- Decompress picture data into a BitMap structure.
  269.  
  270.    SYNOPSIS
  271.     error = DecompBitMap (header, indata, bitmap, mask)
  272.      D0                A0      A1      A2     a3
  273.  
  274.     LONG DecompBitMap (struct CompHeader *, UBYTE *,
  275.                struct BitMap *, PLANEPTR);
  276.  
  277.    FUNCTION
  278.     Decompresses picture data from sbox into a BitMap structure.
  279.     Returns zero if everything happened correctly, or a DEBOXERR_#?
  280.     code.
  281.  
  282.     If the picture has a mask (a flag set in the BMInfo structure),
  283.     the 'mask' parameter must have a pointer to a plane that has the
  284.     same dimensions as the bitmap planes.  If there is no mask, this
  285.     field should be left as NULL.  DEBOXERR_MISSINGPLANE will be
  286.     returned if a mask is needed.
  287.  
  288.     This routine assumes that the bitmap is the same width, height and
  289.     depth as the decompressed data.  If it is not, it will report an
  290.     error, which might happen to be in the form of a GURU.
  291.  
  292.     This can be called without calling DecompBMInfo.  However it is the
  293.     caller's responsibility to set up the BitMap correctly.
  294.  
  295.    INPUTS
  296.     header    - pointer to a CompHeader structure or NULL.  If NULL then
  297.           the indata parameter is assumed to point to the CompHeader
  298.           structure (all sbox'ed data is in the form <header><data>).
  299.     indata    - pointer to the start of a picture compressed data area.
  300.           If header is not NULL then indata should be pointing to the
  301.           <data> and not the <header>.
  302.     bitmap    - a pointer to a fully initialized BitMap structure that is
  303.           the same size as the picture to be decompressed.
  304.     mask    - A PLANEPTR to a mask bitplane of the same dimensions as
  305.           the bitmap's planes.  If a mask is not contained in this
  306.           picture, mask should be NULL.
  307.  
  308.    RESULT
  309.     error    - zero if everything went well.  Non-zero otherwise;  check
  310.           debox.h for DEBOXERR_#? codes.
  311.  
  312.    EXAMPLE
  313.  
  314.    NOTES
  315.     Bitplanes need not be in CHIP RAM.
  316.  
  317.    BUGS
  318.  
  319.    SEE ALSO
  320.     cdtv/debox.h
  321.  
  322. debox.library/DecompBMInfo                         debox.library/DecompBMInfo
  323.  
  324.    NAME
  325.     DecompBMInfo -- Get info for bitmap compressed data.
  326.  
  327.    SYNOPSIS
  328.     outbminfo = DecompBMInfo (bminfo,header, indata)
  329.       D0               A0      A1      A2
  330.  
  331.     struct BMInfo * DecompBMInfo (    struct BMInfo *,
  332.                     struct CompHeader *, UBYTE *);
  333.  
  334.    FUNCTION
  335.     Extracts and allocates a BMInfo structure from a sbox-compressed
  336.     picture file, and returns a pointer to it.  If there is any form of
  337.     error (memory shortage, decompression error, et al), NULL will be
  338.     returned.
  339.  
  340.     The resulting BMInfo structure may be used to prepare a bitmap of
  341.     the correct size, then filled in with DecompBitMap().
  342.  
  343.     'bminfo' can point to a memory block or be NULL.  If a NULL is passed
  344.     the function will attemp to allocate the BMInfo structure.  This
  345.     allocated structure must be freed using FreeBMInfo().  If 'bminfo'
  346.     point to a block of memory, the block must be at least
  347.     the size of BMInfoSize().
  348.  
  349.    INPUTS
  350.     bminfo    - an optional pointer to a BMInfo structure. If a NULL is
  351.           passed then a bitmap structure will be created by this
  352.           function.  The size of the BMInfo structure can be found
  353.           by a call to BMInfoSize().
  354.     header    - pointer to a CompHeader structure or NULL.  If NULL then
  355.           the indata parameter is assumed to point to the CompHeader
  356.           structure (all sbox'ed data is in the form <header><data>).
  357.     indata    - pointer to the start of a picture compressed data area.
  358.           If header is not NULL then indata should be pointing to the
  359.           <data> and not the <header>.
  360.  
  361.    RESULT
  362.     outbminfo-     pointer to filled-out BMInfo structure, or NULL if there
  363.               was an error.  If bminfo was not NULL.
  364.  
  365.    EXAMPLE
  366.  
  367.    NOTES
  368.  
  369.    BUGS
  370.  
  371.    SEE ALSO
  372.  
  373. debox.library/DecompData                             debox.library/DecompData
  374.  
  375.    NAME
  376.     DecompData -- Decompresses squeezed box data segments.
  377.  
  378.    SYNOPSIS
  379.     result = DecompData (header, indata, outdata)
  380.      D0              A0      A1      A2
  381.  
  382.     LONG DecompData (struct CompHeader *, UBYTE *, UBYTE *);
  383.  
  384.    FUNCTION
  385.     This is the general decompression function.  If ci_Type
  386.     DEBOX_UNKNOWN, you should use this function to decompress
  387.     the data.
  388.  
  389.     It is up to you to "know" what to do with the resulting data.
  390.  
  391.    INPUTS
  392.     header    - pointer to a CompHeader structure or NULL.  If NULL then
  393.           the indata parameter is assumed to point to the CompHeader
  394.           structure (all sbox'ed data is in the form <header><data>).
  395.     indata    - pointer to the data to be decompressed.  If header is not
  396.           NULL then indata should be pointing to the <data> and not
  397.           the <header>.
  398.     outdata    - pointer to an area of memory to deposit decompressed data.
  399.           The area must be as large as header->hi_Size.
  400.  
  401.    RESULT
  402.     result -  Positive for the total number of bytes decompressed
  403.           or a negitive DEBOXERR code.
  404.  
  405.    EXAMPLE
  406.  
  407.    NOTES
  408.  
  409.    BUGS
  410.  
  411.    SEE ALSO
  412.  
  413. debox.library/DeleteView                             debox.library/DeleteView
  414.  
  415.    NAME
  416.     DeleteView -- Removes and frees a SuperView structure.
  417.  
  418.    SYNOPSIS
  419.     DeleteView (superview)
  420.                A0
  421.  
  422.     VOID DeleteView (struct SuperView *);
  423.  
  424.    FUNCTION
  425.     Frees everything CreateView() created.  If the SV_ALLOCATED bit
  426.     is set in the SuperView structure, DeleteView() will free it, too.
  427.  
  428.     Make sure some other view is loaded before calling this routine.
  429.     Otherwise, you may get a garbage display.
  430.  
  431.    INPUTS
  432.     superview - pointer to a SuperView structure set up or created by
  433.             CreateView().
  434.  
  435.    RESULT
  436.  
  437.    EXAMPLE
  438.  
  439.    NOTES
  440.  
  441.    BUGS
  442.  
  443.    SEE ALSO
  444.     CreateView()
  445.  
  446. debox.library/FreeBitMap                             debox.library/FreeBitMap
  447.  
  448.    NAME
  449.     FreeBitMap -- Frees a bitmap created with AllocBitMap().
  450.  
  451.    SYNOPSIS
  452.     FreeBitMap (bitmap)
  453.               A0
  454.  
  455.     void FreeBitMap (struct BitMap *);
  456.  
  457.    FUNCTION
  458.     Frees everything that AllocBitMap() created.  The routine will free
  459.     with a depth >8 bitplanes also.
  460.  
  461.    INPUTS
  462.     bitmap    - a pointer to a bitmap structure created with
  463.           AllocBitMap().
  464.  
  465.    RESULT
  466.  
  467.    EXAMPLE
  468.  
  469.    NOTES
  470.  
  471.    BUGS
  472.  
  473.    SEE ALSO
  474.  
  475. debox.library/FreeBMInfo                             debox.library/FreeBMInfo
  476.  
  477.    NAME
  478.     FreeBMInfo -- Frees the BMInfo structure.
  479.  
  480.    SYNOPSIS
  481.     FreeBMInfo (bminfo)
  482.               A0
  483.  
  484.     void FreeBMInfo (struct BMInfo *);
  485.  
  486.    FUNCTION
  487.     Frees a BMInfo structure created by DecompBMInfo().  This will free
  488.     the entire area of the BMInfo structure, including the included
  489.     color map and range info section.
  490.  
  491.    INPUTS
  492.     bminfo    - pointer to a BMInfo structure that was returned from a
  493.           call to DecompBMInfo().
  494.  
  495.    RESULT
  496.  
  497.    EXAMPLE
  498.  
  499.    NOTES
  500.  
  501.    BUGS
  502.  
  503.    SEE ALSO
  504.     DecompBMInfo()
  505.  
  506. debox.library/HeaderSize                             debox.library/HeaderSize
  507.  
  508.    NAME
  509.     HeaderSize -- Report the size of the header.
  510.  
  511.    SYNOPSIS
  512.     size = HeaderSize (header)
  513.      D0               A0
  514.  
  515.     ULONG HeaderSize (struct CompHeader *);
  516.  
  517.    FUNCTION
  518.     Returns the size of the header based on the version.  Right now it
  519.     will only handle version 1 headers.  If a NULL is passed - Version 1
  520.     header size will be returned.
  521.  
  522.    INPUTS
  523.     header    - pointer to CompHeader structure
  524.  
  525.    RESULT
  526.  
  527.    EXAMPLE
  528.  
  529.    NOTES
  530.  
  531.    BUGS
  532.  
  533.    SEE ALSO
  534.     HeaderOffset()
  535.  
  536. debox.library/MemSet                                     debox.library/MemSet
  537.  
  538.    NAME
  539.     MemSet -- General purpose memory-setting routine.
  540.  
  541.    SYNOPSIS
  542.     MemSet (buffer, value, size)
  543.           A0     D0     D1
  544.  
  545.     void MemSet (void *, UBYTE, ULONG);
  546.  
  547.    FUNCTION
  548.     Fills the 'buffer' with the low order byte of 'value' quickly.
  549.  
  550.    INPUTS
  551.     buffer    - a pointer to a buffer to be filled.
  552.     value    - character to fill the buffer.
  553.     size    - size of area to be filled.
  554.  
  555.    RESULT
  556.  
  557.    EXAMPLE
  558.  
  559.    NOTES
  560.  
  561.    BUGS
  562.  
  563.    SEE ALSO
  564.  
  565. debox.library/NextComp                                 debox.library/NextComp
  566.  
  567.    NAME
  568.     NextComp -- Go to next decompression data area.
  569.  
  570.    SYNOPSIS
  571.     data = NextComp (header, indata)
  572.      D0             A0      A1
  573.  
  574.     UBYTE * NextComp (struct CompHeader *, UBYTE *);
  575.  
  576.    FUNCTION
  577.     NextComp() returns a pointer the byte just after the current
  578.     decompression block.  If, for example, DEBOX files were joined
  579.     together and loaded in as one file, NextComp() could be used to
  580.     get the positions of all the "things" in the file.  If an error
  581.     occurs, such as the passed data is invalid, NULL is returned.
  582.  
  583.    INPUTS
  584.     header    - pointer to a CompHeader structure or NULL.  If NULL then
  585.           the indata parameter is assumed to point to the CompHeader
  586.           structure (all sbox'ed data is in the form <header><data>).
  587.     indata    - pointer to the data to be skipped.  If header is not NULL
  588.           then indata should be pointing to the <data> and not
  589.           the <header>.
  590.  
  591.    RESULT
  592.     data    - pointer to next "thing" in file, or NULL if an error
  593.           occurred.
  594.  
  595.    EXAMPLE
  596.  
  597.    NOTES
  598.  
  599.    BUGS
  600.  
  601.    SEE ALSO
  602.  
  603.